<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.3.1"/>
<title>Open Event Machine API: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">Open Event Machine API
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.3.1 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li><a href="examples.html"><span>Examples</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('index.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">Open Event Machine API Documentation</div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="section_1"></a>
General</h1>
<p>Event Machine (EM) is an architectural abstraction and framework of an event driven multicore optimized processing concept originally developed for networking data plane. It offers an easy programming concept for scalable and dynamically load balanced multicore applications with a very low overhead run-to-completion principle.</p>
<p>Main elements in the concept are events, queues, scheduler, dispatcher and the execution objects (EO). Event is an application specific piece of data (like a message or a network packet) describing work, something to do. Any processing in EM must be triggered by an event. Events are sent to asynchronous application specific queues. A single thread on all cores of an EM instance runs a dispatcher loop (a "core" is used here to refer to a core or one HW thread on multi-threaded cores). Dispatcher interfaces with the scheduler and asks for an event. Scheduler evaluates the state of all queues and gives the highest priority event to the dispatcher, which forwards it to the EO mapped to the queue the event came from by calling the registered receive function. As the event is handled and receive function returns, the next event is received from the scheduler and again forwarded to the mapped EO. This happens in parallel on all cores included. Everything is highly efficient run to completion single thread, no context switching nor pre-emption (priorities are handled by the scheduler). EM can run on bare metal for best performance or under an operating system with special arrangements (e.g. one thread per core with thread affinity).</p>
<p>The concept and this API are made to be easy to implement for multiple general purpose or networking oriented multicore packet processing systems on chip, which typically also contain accelerators for packet processing needs. Efficient integration with modern HW accelerators has been a major driver in EM concept.</p>
<p>One general principle of this API is that all calls are multicore safe, i.e. no data structure gets broken, if calls are simultaneously made by multiple cores, but unless explicitly documented per API call, the application also needs to take the parallel world into consideration. For example if one core asks for a queue mode and another one changes the mode at the same time, the returned mode may be invalid (valid data, but the old or the new!). Thus modifications should be done under atomic context (if load balancing is used) or otherwise synchronized by the application. One simple way of achieving this is to use one EO with an atomic queue to do all the management functionality. That guarantees synchronized operations (but also serializes them limiting performance)</p>
<p>EM_64_BIT or EM_32_BIT (needs to be defined at makefile) defines whether (most of) the types used in the API are 32 or 64 bits wide. NOTE, that this is a major decision, since it may limit value passing between different systems using the defined types directly. Using 64-bits may allow more efficient underlying implementation, as more data can be coded in 64-bit identifiers for instance.</p>
<h1><a class="anchor" id="section_2"></a>
Some principles</h1>
<ul>
<li>This API attempts to guide towards a portable application architecture, but is not defined for portability by re-compilation. Many things are system specific giving more possibilities for efficient use of HW resources.</li>
<li>EM does not define event content (one exception, see <a class="el" href="event__machine_8h.html#a22fcb41f303628eebe4f0b45b6c64ab0" title="Allocate an event.">em_alloc()</a>). This is a choice made for performance, since most HW devices use proprietary descriptors. This API enables to use those directly.</li>
<li>EM does not define detailed queue scheduling disciplines or API to set those up (or actually anything to configure a system). The priority value in this API is a (mapped) system specific QoS class label only</li>
<li>In general EM does not implement full SW platform or middleware solution, it implements a sub- set of such, a driver level part. For best performance it can be used directly from applications.</li>
</ul>
<h1><a class="anchor" id="section_3"></a>
Files</h1>
<ul>
<li><a class="el" href="event__machine_8h.html" title="Event Machine API v1.0.">event_machine.h</a><ul>
<li>Event Machine main API, all applications need to include</li>
</ul>
</li>
<li><a class="el" href="event__machine__types_8h.html" title="Event Machine basic types.">event_machine_types.h</a><ul>
<li>Event Machine basic types, included by <a class="el" href="event__machine_8h.html" title="Event Machine API v1.0.">event_machine.h</a></li>
</ul>
</li>
<li><a class="el" href="event__machine__helper_8h.html" title="Event Machine helper functions and macros.">event_machine_helper.h</a><ul>
<li>optional helper routines</li>
</ul>
</li>
<li><a class="el" href="event__machine__group_8h.html" title="Event Machine optional fork-join helper.">event_machine_group.h</a><ul>
<li>optional event group feature for fork-join - type of operations using events</li>
</ul>
</li>
<li>event_machine_hw_config.h<ul>
<li>HW specific constants and enumerations, included by <a class="el" href="event__machine__types_8h.html" title="Event Machine basic types.">event_machine_types.h</a></li>
</ul>
</li>
<li>event_machine_hw_specific.h<ul>
<li>HW specific functions and macros, included by <a class="el" href="event__machine_8h.html" title="Event Machine API v1.0.">event_machine.h</a> </li>
</ul>
</li>
</ul>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Wed Aug 7 2013 15:17:39 for Open Event Machine API by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.3.1 </li>
  </ul>
</div>
</body>
</html>
